<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>29.3. Memory Objects</title>
<link rel="stylesheet" href="dbstyle.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.72.0">
<link rel="start" href="index.html" title="Programmer's Reference Guide">
<link rel="up" href="zend.memory.html" title="Chapter 29. Zend_Memory">
<link rel="prev" href="zend.memory.memory-manager.html" title="29.2. Memory Manager">
<link rel="next" href="zend.mime.html" title="Chapter 30. Zend_Mime">
<link rel="chapter" href="introduction.html" title="Chapter 1. Introduction to Zend Framework">
<link rel="chapter" href="zend.acl.html" title="Chapter 2. Zend_Acl">
<link rel="chapter" href="zend.auth.html" title="Chapter 3. Zend_Auth">
<link rel="chapter" href="zend.cache.html" title="Chapter 4. Zend_Cache">
<link rel="chapter" href="zend.config.html" title="Chapter 5. Zend_Config">
<link rel="chapter" href="zend.console.getopt.html" title="Chapter 6. Zend_Console_Getopt">
<link rel="chapter" href="zend.controller.html" title="Chapter 7. Zend_Controller">
<link rel="chapter" href="zend.currency.html" title="Chapter 8. Zend_Currency">
<link rel="chapter" href="zend.date.html" title="Chapter 9. Zend_Date">
<link rel="chapter" href="zend.db.html" title="Chapter 10. Zend_Db">
<link rel="chapter" href="zend.debug.html" title="Chapter 11. Zend_Debug">
<link rel="chapter" href="zend.dojo.html" title="Chapter 12. Zend_Dojo">
<link rel="chapter" href="zend.dom.html" title="Chapter 13. Zend_Dom">
<link rel="chapter" href="zend.exception.html" title="Chapter 14. Zend_Exception">
<link rel="chapter" href="zend.feed.html" title="Chapter 15. Zend_Feed">
<link rel="chapter" href="zend.filter.html" title="Chapter 16. Zend_Filter">
<link rel="chapter" href="zend.form.html" title="Chapter 17. Zend_Form">
<link rel="chapter" href="zend.gdata.html" title="Chapter 18. Zend_Gdata">
<link rel="chapter" href="zend.http.html" title="Chapter 19. Zend_Http">
<link rel="chapter" href="zend.infocard.html" title="Chapter 20. Zend_InfoCard">
<link rel="chapter" href="zend.json.html" title="Chapter 21. Zend_Json">
<link rel="chapter" href="zend.layout.html" title="Chapter 22. Zend_Layout">
<link rel="chapter" href="zend.ldap.html" title="Chapter 23. Zend_Ldap">
<link rel="chapter" href="zend.loader.html" title="Chapter 24. Zend_Loader">
<link rel="chapter" href="zend.locale.html" title="Chapter 25. Zend_Locale">
<link rel="chapter" href="zend.log.html" title="Chapter 26. Zend_Log">
<link rel="chapter" href="zend.mail.html" title="Chapter 27. Zend_Mail">
<link rel="chapter" href="zend.measure.html" title="Chapter 28. Zend_Measure">
<link rel="chapter" href="zend.memory.html" title="Chapter 29. Zend_Memory">
<link rel="chapter" href="zend.mime.html" title="Chapter 30. Zend_Mime">
<link rel="chapter" href="zend.openid.html" title="Chapter 31. Zend_OpenId">
<link rel="chapter" href="zend.paginator.html" title="Chapter 32. Zend_Paginator">
<link rel="chapter" href="zend.pdf.html" title="Chapter 33. Zend_Pdf">
<link rel="chapter" href="zend.registry.html" title="Chapter 34. Zend_Registry">
<link rel="chapter" href="zend.rest.html" title="Chapter 35. Zend_Rest">
<link rel="chapter" href="zend.search.lucene.html" title="Chapter 36. Zend_Search_Lucene">
<link rel="chapter" href="zend.server.html" title="Chapter 37. Zend_Server">
<link rel="chapter" href="zend.service.html" title="Chapter 38. Zend_Service">
<link rel="chapter" href="zend.session.html" title="Chapter 39. Zend_Session">
<link rel="chapter" href="zend.soap.html" title="Chapter 40. Zend_Soap">
<link rel="chapter" href="zend.test.html" title="Chapter 41. Zend_Test">
<link rel="chapter" href="zend.text.html" title="Chapter 42. Zend_Text">
<link rel="chapter" href="zend.timesync.html" title="Chapter 43. Zend_TimeSync">
<link rel="chapter" href="zend.translate.html" title="Chapter 44. Zend_Translate">
<link rel="chapter" href="zend.uri.html" title="Chapter 45. Zend_Uri">
<link rel="chapter" href="zend.validate.html" title="Chapter 46. Zend_Validate">
<link rel="chapter" href="zend.version.html" title="Chapter 47. Zend_Version">
<link rel="chapter" href="zend.view.html" title="Chapter 48. Zend_View">
<link rel="chapter" href="zend.xmlrpc.html" title="Chapter 49. Zend_XmlRpc">
<link rel="appendix" href="requirements.html" title="Appendix A. Zend Framework Requirements">
<link rel="appendix" href="coding-standard.html" title="Appendix B. Zend Framework Coding Standard for PHP">
<link rel="appendix" href="copyrights.html" title="Appendix C. Copyright Information">
<link rel="index" href="the.index.html" title="Index">
<link rel="subsection" href="zend.memory.memory-objects.html#zend.memory.memory-objects.movable" title="29.3.1. Movable">
<link rel="subsection" href="zend.memory.memory-objects.html#zend.memory.memory-objects.locked" title="29.3.2. Locked">
<link rel="subsection" href="zend.memory.memory-objects.html#zend.memory.memory-objects.value" title="29.3.3. Memory container 'value' property.">
<link rel="subsection" href="zend.memory.memory-objects.html#zend.memory.memory-objects.api" title="29.3.4. Memory container interface">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader"><table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">29.3. Memory Objects</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="zend.memory.memory-manager.html">Prev</a> </td>
<th width="60%" align="center">Chapter 29. Zend_Memory</th>
<td width="20%" align="right"> <a accesskey="n" href="zend.mime.html">Next</a>
</td>
</tr>
</table></div>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="zend.memory.memory-objects"></a>29.3. Memory Objects</h2></div></div></div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.memory.memory-objects.movable"></a>29.3.1. Movable</h3></div></div></div>
<p>
            Create movable memory objects using the <code class="code">create([$data])</code>
            method of the memory manager:
            </p>
<pre class="programlisting">&lt;?php
$memObject = $memoryManager-&gt;create($data);
            </pre>
<p>
        </p>
<p>
            "Movable" means that such objects may be swapped and unloaded from
            memory and then loaded when application code accesses the object.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.memory.memory-objects.locked"></a>29.3.2. Locked</h3></div></div></div>
<p>
            Create locked memory objects using the <code class="code">createLocked([$data])</code>
            method of the memory manager:
            </p>
<pre class="programlisting">&lt;?php
$memObject = $memoryManager-&gt;createLocked($data);
            </pre>
<p>
        </p>
<p>
            "Locked" means that such objects are never swapped and unloaded
            from memory.
        </p>
<p>
            Locked objects provides the same interface as movable objects
            (<code class="code">Zend_Memory_Container_Interface</code>).
            So locked object can be used in any place instead of movable objects.
        </p>
<p>
            It's useful if an application or developer can decide, that some
            objects should never be swapped, based on performance considerations.
        </p>
<p>
            Access to locked objects is faster, because the memory manager doesn't
            need to track changes for these objects.
        </p>
<p>
            The locked objects class (<code class="code">Zend_Memory_Container_Locked</code>)
            guarantees virtually the same performance as working with a string
            variable.  The overhead is a single dereference to get the class property.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.memory.memory-objects.value"></a>29.3.3. Memory container 'value' property.</h3></div></div></div>
<p>
            Use the memory container (movable or locked) '<code class="code">value</code>'
            property to operate with memory object data:
            </p>
<pre class="programlisting">&lt;?php
$memObject = $memoryManager-&gt;create($data);

echo $memObject-&gt;value;

$memObject-&gt;value = $newValue;

$memObject-&gt;value[$index] = '_';

echo ord($memObject-&gt;value[$index1]);

$memObject-&gt;value = substr($memObject-&gt;value, $start, $length);
            </pre>
<p>
        </p>
<p>
            An alternative way to access memory object data is to use the
            <a href="zend.memory.memory-objects.html#zend.memory.memory-objects.api.getRef" title="29.3.4.1. getRef() method"><code class="code">getRef()</code></a>
            method.  This method <span class="emphasis"><em>must</em></span> be used for PHP
            versions before 5.2.  It also may have to be used in some other
            cases for performance reasons.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.memory.memory-objects.api"></a>29.3.4. Memory container interface</h3></div></div></div>
<p>
            Memory container provides the following methods:
        </p>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.memory.memory-objects.api.getRef"></a>29.3.4.1. getRef() method</h4></div></div></div>
<pre class="programlisting">&lt;?php
public function &amp;getRef();
            </pre>
<p>
                The <code class="code">getRef()</code> method returns reference to the object value.
            </p>
<p>
                Movable objects are loaded from the cache at this moment if the
                object is not already in memory.  If the object is loaded from
                the cache, this might cause swapping of other objects if the
                memory limit would be exceeded by having all the managed
                objects in memory.
            </p>
<p>
                The <code class="code">getRef()</code> method <span class="emphasis"><em>must</em></span> be
                used to access memory object data for PHP versions before 5.2.
            </p>
<p>
                Tracking changes to data needs additional resources.
                The <code class="code">getRef()</code> method returns reference to string,
                which is changed directly by user application.
                So, it's a good idea to use the <code class="code">getRef()</code> method
                for value data processing:
                </p>
<pre class="programlisting">&lt;?php
$memObject = $memoryManager-&gt;create($data);

$value = &amp;$memObject-&gt;getRef();

for ($count = 0; $count &lt; strlen($value); $count++) {
    $char = $value[$count];
    ...
}
                </pre>
<p>
            </p>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.memory.memory-objects.api.touch"></a>29.3.4.2. touch() method</h4></div></div></div>
<pre class="programlisting">&lt;?php
public function touch();
            </pre>
<p>
                The <code class="code">touch()</code> method should be used in common with
                <code class="code">getRef()</code>. It signals that object value has been changed:
                </p>
<pre class="programlisting">&lt;?php
$memObject = $memoryManager-&gt;create($data);
...

$value = &amp;$memObject-&gt;getRef();

for ($count = 0; $count &lt; strlen($value); $count++) {
    ...
    if ($condition) {
        $value[$count] = $char;
    }
    ...
}

$memObject-&gt;touch();
                </pre>
<p>

            </p>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.memory.memory-objects.api.lock"></a>29.3.4.3. lock() method</h4></div></div></div>
<pre class="programlisting">&lt;?php
public function lock();
            </pre>
<p>
                The <code class="code">lock()</code> methods locks object in memory.
                It should be used to prevent swapping of some objects you choose.
                Normally, this is not necessary, because the memory manager uses
                an intelligent algorithm to choose candidates for swapping.
                But if you exactly know, that at at this part of code some
                objects should not be swapped, you may lock them.
            </p>
<p>
                Locking objects in memory also guarantees that reference
                returned by the <code class="code">getRef()</code> method is valid until you
                unlock the object:
                </p>
<pre class="programlisting">&lt;?php
$memObject1 = $memoryManager-&gt;create($data1);
$memObject2 = $memoryManager-&gt;create($data2);
...

$memObject1-&gt;lock();
$memObject2-&gt;lock();

$value1 = &amp;$memObject1-&gt;getRef();
$value2 = &amp;$memObject2-&gt;getRef();

for ($count = 0; $count &lt; strlen($value2); $count++) {
    $value1 .= $value2[$count];
}

$memObject1-&gt;touch();
$memObject1-&gt;unlock();
$memObject2-&gt;unlock();
                </pre>
<p>
            </p>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.memory.memory-objects.api.unlock"></a>29.3.4.4. unlock() method</h4></div></div></div>
<pre class="programlisting">&lt;?php
public function unlock();
            </pre>
<p>
                <code class="code">unlock()</code> method unlocks object when it's no longer
                necessary to be locked. See the example above.
            </p>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.memory.memory-objects.api.isLocked"></a>29.3.4.5. isLocked() method</h4></div></div></div>
<pre class="programlisting">&lt;?php
public function isLocked();
            </pre>
<p>
                The <code class="code">isLocked()</code> method can be used to check if
                object is locked.  It returns <code class="code">true</code> if the object
                is locked, or <code class="code">false</code> if it is not locked.
                This is always <code class="code">true</code> for "locked" objects,
                and may be either <code class="code">true</code> or <code class="code">false</code>
                for "movable" objects.
            </p>
</div>
</div>
</div>
<div class="navfooter"><table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="zend.memory.memory-manager.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="zend.memory.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="zend.mime.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">29.2. Memory Manager </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> Chapter 30. Zend_Mime</td>
</tr>
</table></div>
<div class="revinfo"></div>
</body>
</html>
